// The caller may implement the SymbolSupplier abstract base class
// to provide symbols for a given module.
#ifndef LONGKEY_BREAKPAD_PROCESSOR_SYMBOL_SUPPLIER_H_
#define LONGKEY_BREAKPAD_PROCESSOR_SYMBOL_SUPPLIER_H_

#include <string>

namespace longkey_breakpad
{
	using std::string;
	class CodeModule;
	class SystemInfo;

	class SymbolSupplier
	{
	public:
		// Result type for GetSymbolFile
		enum SymbolResult {
			// no symbols were found, but continue processing
			NOT_FOUND,

			// symbols were found, and the path has been placed in symbol_file
			FOUND,

			// stops processing the minidump immediately
			INTERRUPT
		};

		virtual ~SymbolSupplier() {}

		// Retrieves the symbol file for the given CodeModule, placing the
		// path in symbol_file if successful.  system_info contains strings
		// identifying the operating system and CPU; SymbolSupplier may use
		// to help locate the symbol file.  system_info may be NULL or its
		// fields may be empty if these values are unknown.  symbol_file
		// must be a pointer to a valid string
		virtual SymbolResult GetSymbolFile(const CodeModule *module,
			const SystemInfo *system_info, string *symbol_file) = 0;

		// Same as above, except also places symbol data into symbol_data.
		// If symbol_data is NULL, the data is not returned.
		// TODO(nealsid) Once we have symbol data caching behavior implemented
		// investigate making all symbol suppliers implement all methods,
		// and make this pure virtual
		virtual SymbolResult GetSymbolFile(const CodeModule *module,
			const SystemInfo *system_info, string *symbol_file, string *symbol_data) = 0;

		// Same as above, except allocates data buffer on heap and then places the
		// symbol data into the buffer as C-string.
		// SymbolSupplier is responsible for deleting the data buffer. After the call
		// to GetCStringSymbolData(), the caller should call FreeSymbolData(const
		// Module *module) once the data buffer is no longer needed.
		// If symbol_data is not NULL, symbol supplier won't return FOUND unless it
		// returns a valid buffer in symbol_data, e.g., returns INTERRUPT on memory
		// allocation failure.
		virtual SymbolResult GetCStringSymbolData(const CodeModule *module,
			const SystemInfo *system_info, string *symbol_file, char **symbol_data) = 0;

		// Frees the data buffer allocated for the module in GetCStringSymbolData.
		virtual void FreeSymbolData(const CodeModule *module) = 0;
	};
}

#endif	// LONGKEY_BREAKPAD_PROCESSOR_SYMBOL_SUPPLIER_H_